QuickTime 3 Reference

Previous | Chapter Top | Chapter Contents

Video Digitizer Components Reference

Constants

Input Formats

You use the VDGetInputFormat function to find out the video format employed by a specified input. QuickTime defines one new constant that you can use for video digitizers that support a tuner input:

enum {
    tvTunerIn           = 6
};

Constant description

tvTunerIn
The input video signal is from the television tuner connection.

Video Digitizer Component Functions

Controlling Compressed Source Devices

In QuickTime 1.5, video digitizers could provide compressed data directly to clients. However, there was no way to preflight the settings for compression. In QuickTime 2.1, a new function, VDGetCompressionTime , has been added to allow the video digitizer to quantify the compression time for the actual quality levels that will be used.

VDGetCompressionTime

Your component receives the VDGetCompressionTime request whenever a client of the digitizer wants to confirm or quantify its compression settings.

pascal VideoDigitizerError VDGetCompressionTime (
                     VideoDigitizerComponent ci,
                     OSType compressionType,
                     short depth,
                     Rect *srcRect,
                     CodecQ *spatialQuality,
                     CodecQ *temporalQuality,
                     unsigned long *compressTime);
ci
Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.
compressionType
Specifies a compressor type. This value corresponds to the component subtype of the compressor component. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about compressor types, including valid values for this parameter.
depth
Specifies the depth at which the image is to be compressed. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 33, 34, 36, and 40 indicate 1-bit, 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images.
srcRect
Contains a pointer to a rectangle defining the portion of the source image to compress.
spatialQuality
Contains a pointer to a field containing the desired compressed image quality. The compressor sets this field to the closest actual quality that it can achieve. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values. A value of nil indicates that the client does not want this information.
temporalQuality
Contains a pointer to a field containing the desired sequence temporal quality. The compressor sets this field to the closest actual quality that it can achieve. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for valid values. A value of nil indicates that the client does not want this information.
compressTime
Contains a pointer to a field to receive the compression time, in milliseconds. If your component cannot determine the amount of time required to compress the image, set this field to 0. A value of nil indicates that the client does not want this information.

DISCUSSION

The sequence grabber's video compression settings dialog box uses this function to snap the quality slider to the correct value when working with a compression type that is specified by the video digitizer.

Your component should return a long integer indicating the maximum number of milliseconds it would require to compress the specified image.

RESULT CODES

noErr

0

No error
paramErr

-50

Invalid parameter specified

 

Controlling Digitization

This section describes one new video digitizer component function, VDSetDataRate , that instructs your video digitizer component to observe a specified rate of data delivery.

VDSetDataRate

The VDSetDataRate function instructs your video digitizer component to limit the rate at which it delivers compressed, digitized video data.

pascal VideoDigitizerError VDSetDataRate (
                     VideoDigitizerComponent ci,
                     long bytesPerSecond);
ci
Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.
bytesPerSecond
Specifies the maximum data rate requested by the application. This parameter is set to 0 to remove any data-rate restrictions.

DISCUSSION

This function is valid only for video digitizer components that can deliver compressed video (that is, components that support the VDCompressOneFrameAsync function). Components that support data-rate limiting set the codecInfoDoesRateConstrain flag to 1 in the compressFlags field of the VDCompressionList structure returned by the component in response to the VDGetCompressionTypes function.

Your video digitizer component should return this data-rate limit in the bytesPerSecond parameter of the existing VDGetDataRate function.

Controlling Packet Size

VDSetPreferredPacketSize

The VDSetPreferredPacketSize function sets the preferred packet size for video digitizing.

pascal VideoDigitizerError VDSetPreferredPacketSize(
                     VideoDigitizerComponent ci,
                     long preferredPacketSizeInBytes);
ci
Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.
preferredPacketSizeInBytes
The preferred packet size in bytes.

DESCRIPTION

This function was added in QuickTime 2.5 to support video conferencing applications.

Utility Functions

This section describes two new utility functions that may be supported by some video digitizer components.

The VDGetTimeCode function allows an application to retrieve timecode information.

The VDGetSoundInputSource function allows an application to retrieve information about a digitizer's sound input source.

VDGetTimeCode

The VDGetTimeCode function instructs your video digitizer component to return timecode information for the incoming video signal.

pascal VideoDigitizerError VDGetTimeCode (
                     VideoDigitizerComponent ci,
                     TimeRecord *atTime,
                     void *timeCodeFormat,
                     void *timeCodeTime);
ci
Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.
atTime
Specifies a location to receive the QuickTime movie time value corresponding to the timecode information.
timeCodeFormat
Contains a pointer to a timecode definition structure. Your video digitizer component returns the movie's timecode definition information.
timeCodeTime
Contains a pointer to a timecode record structure. Your video digitizer component returns the time value corresponding to the movie time contained in the atTime parameter.

DISCUSSION

Typically, this function is called once, at the beginning of a capture session. The use of VDGetTimeCode assumes that the timecoding for the entire capture session will be continuous.

For more information about the timecode data structures, see "Movie Toolbox: Time and Space."

VDGetSoundInputSource

The VDGetSoundInputSource function instructs your video digitizer component to return the sound input source associated with a particular video input.

pascal VideoDigitizerError VDGetSoundInputSource (
                     VideoDigitizerComponent ci,
                     long videoInput,
                     long *soundInput);
ci
Specifies the video digitizer component for the request. Applications obtain this reference from the Component Manager's OpenComponent function.
videoInput
Specifies the input video source for this request. Video digitizer components number video sources sequentially, starting at 0. So, to request information about the first video source, an application sets this parameter to 0. Applications can get the number of video sources supported by a video digitizer component by calling the VDGetNumberOfInputs function.
soundInput
The sound input index to use with the sound input driver returned by VDGetSoundInputDriver .

DISCUSSION

Some video digitizers may associate different sound inputs with each video input. The VDGetSoundInputDriver function returns the name of the sound input driver that the sound input is associated with.

 

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents